@jsenv/snapshot 2.8.3 → 2.8.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jsenv/snapshot",
-  "version": "2.8.3",
+  "version": "2.8.5",
   "description": "Snapshot testing",
   "license": "MIT",
   "author": {
@@ -35,9 +35,9 @@
   "dependencies": {
     "@jsenv/assert": "4.1.15",
     "@jsenv/ast": "6.2.14",
-    "@jsenv/exception": "1.0.1",
-    "@jsenv/filesystem": "4.9.9",
-    "@jsenv/terminal-recorder": "1.4.3",
+    "@jsenv/exception": "1.0.2",
+    "@jsenv/filesystem": "4.9.10",
+    "@jsenv/terminal-recorder": "1.4.4",
     "@jsenv/urls": "2.5.2",
     "@jsenv/utils": "2.1.2",
     "ansi-regex": "6.0.1",

package/src/filesystem_snapshot.js

@@ -180,7 +180,7 @@ export const takeDirectorySnapshot = (
     return URL_META.urlChildMayMatch({
       url,
       associations,
-      predicate: (meta) => Boolean(meta.action),
+      predicate: (meta) => meta.action && meta.action !== "ignore",
     });
   };
   const shouldIncludeFile = (url) => {
@@ -188,9 +188,13 @@ export const takeDirectorySnapshot = (
       url,
       associations,
     });
-    return meta.action === true || meta.action === "presence_only";
+    return (
+      meta.action === true ||
+      meta.action === "compare" ||
+      meta.action === "compare_presence_only"
+    );
   };
-  const shouldCompareFile = (url) => {
+  const shouldCompareFileContent = (url) => {
     const meta = URL_META.applyAssociations({
       url,
       associations,
@@ -200,7 +204,7 @@ export const takeDirectorySnapshot = (
   const directorySnapshot = createDirectorySnapshot(directoryUrl, {
     shouldVisitDirectory,
     shouldIncludeFile,
-    shouldCompareFile,
+    shouldCompareFileContent,
     clean: true,
   });
   return {
@@ -209,7 +213,7 @@ export const takeDirectorySnapshot = (
       const nextDirectorySnapshot = createDirectorySnapshot(directoryUrl, {
         shouldVisitDirectory,
         shouldIncludeFile,
-        shouldCompareFile,
+        shouldCompareFileContent,
       });
       directorySnapshot.compare(nextDirectorySnapshot, { throwWhenDiff });
     },
@@ -237,7 +241,7 @@ export const takeDirectorySnapshot = (
 };
 const createDirectorySnapshot = (
   directoryUrl,
-  { shouldVisitDirectory, shouldIncludeFile, shouldCompareFile, clean },
+  { shouldVisitDirectory, shouldIncludeFile, shouldCompareFileContent, clean },
 ) => {
   const directorySnapshot = {
     type: "directory",
@@ -322,7 +326,7 @@ ${extraUrls.join("\n")}`);
       // content
       {
         for (const relativeUrl of relativeUrls) {
-          if (!shouldCompareFile(new URL(relativeUrl, directoryUrl))) {
+          if (!shouldCompareFileContent(new URL(relativeUrl, directoryUrl))) {
             continue;
           }
           const snapshot = directoryContentSnapshot[relativeUrl];
@@ -384,7 +388,7 @@ ${extraUrls.join("\n")}`);
           {
             shouldVisitDirectory,
             shouldIncludeFile,
-            shouldCompareFile,
+            shouldCompareFileContent,
             clean,
           },
         );

package/src/side_effects/create_capture_side_effects.js

@@ -4,13 +4,15 @@ import { filesystemSideEffects } from "./filesystem/filesystem_side_effects.js";
 import { logSideEffects } from "./log/log_side_effects.js";
 
 export const createCaptureSideEffects = ({
+  sourceFileUrl,
   logEffects = true,
   filesystemEffects = true,
+  filesystemActions,
   rootDirectoryUrl,
   replaceFilesystemWellKnownValues = createReplaceFilesystemWellKnownValues({
     rootDirectoryUrl,
   }),
-} = {}) => {
+}) => {
   const detectors = [];
   if (logEffects) {
     detectors.push(logSideEffects(logEffects === true ? {} : logEffects));
@@ -20,7 +22,9 @@ export const createCaptureSideEffects = ({
     filesystemSideEffectsDetector = filesystemSideEffects(
       filesystemEffects === true ? {} : filesystemEffects,
       {
+        sourceFileUrl,
         replaceFilesystemWellKnownValues,
+        filesystemActions,
       },
     );
     detectors.push(filesystemSideEffectsDetector);

package/src/side_effects/filesystem/filesystem_side_effects.js

@@ -7,17 +7,16 @@ import { groupFileSideEffectsPerDirectory } from "./group_file_side_effects_per_
 import { spyFilesystemCalls } from "./spy_filesystem_calls.js";
 
 const filesystemSideEffectsOptionsDefault = {
-  include: null,
   preserve: false,
   baseDirectory: "",
-  textualFilesIntoDirectory: false,
+  textualFilesInline: false,
 };
 const INLINE_MAX_LINES = 20;
 const INLINE_MAX_LENGTH = 2000;
 
 export const filesystemSideEffects = (
   filesystemSideEffectsOptions,
-  { replaceFilesystemWellKnownValues },
+  { sourceFileUrl, filesystemActions, replaceFilesystemWellKnownValues },
 ) => {
   filesystemSideEffectsOptions = {
     ...filesystemSideEffectsOptionsDefault,
@@ -42,10 +41,11 @@ export const filesystemSideEffects = (
     name: "filesystem",
     setBaseDirectory,
     install: (addSideEffect, { addSkippableHandler, addFinallyCallback }) => {
-      let { include, preserve, textualFilesIntoDirectory } =
-        filesystemSideEffectsOptions;
+      let { preserve, textualFilesInline } = filesystemSideEffectsOptions;
       if (filesystemSideEffectsOptions.baseDirectory) {
         setBaseDirectory(filesystemSideEffectsOptions.baseDirectory);
+      } else if (sourceFileUrl) {
+        setBaseDirectory(new URL("./", sourceFileUrl));
       }
       const getUrlRelativeToBase = (url) => {
         if (baseDirectory) {
@@ -155,7 +155,7 @@ export const filesystemSideEffects = (
                     if (outDirectoryReason) {
                       const outUrlRelativeToCommonDirectory = urlToRelativeUrl(
                         text.urlInsideOutDirectory,
-                        options.sideEffectFileUrl,
+                        options.sideEffectMdFileUrl,
                       );
                       groupMd += `${"#".repeat(2)} ${urlRelativeToCommonDirectory}
 ${renderFileContent(
@@ -193,7 +193,7 @@ ${renderFileContent(
                     );
                     const commonDirectoryOutRelativeUrl = urlToRelativeUrl(
                       commonDirectoryOutUrl,
-                      options.sideEffectFileUrl,
+                      options.sideEffectMdFileUrl,
                       { preferRelativeNotation: true },
                     );
                     return {
@@ -219,12 +219,14 @@ ${renderFileContent(
             const isTextual = CONTENT_TYPE.isTextual(contentType);
             let outDirectoryReason;
             if (isTextual) {
-              if (textualFilesIntoDirectory) {
-                outDirectoryReason = "textual_in_directory_option";
-              } else if (String(buffer).split("\n").length > INLINE_MAX_LINES) {
-                outDirectoryReason = "lot_of_lines";
-              } else if (buffer.size > INLINE_MAX_LENGTH) {
-                outDirectoryReason = "lot_of_chars";
+              if (textualFilesInline) {
+                if (String(buffer).split("\n").length > INLINE_MAX_LINES) {
+                  outDirectoryReason = "lot_of_lines";
+                } else if (buffer.size > INLINE_MAX_LENGTH) {
+                  outDirectoryReason = "lot_of_chars";
+                }
+              } else {
+                outDirectoryReason = "text";
               }
             } else {
               outDirectoryReason = "binary";
@@ -240,7 +242,7 @@ ${renderFileContent(
                 outDirectoryReason,
               },
               render: {
-                md: ({ sideEffectFileUrl, generateOutFileUrl }) => {
+                md: ({ sideEffectMdFileUrl, generateOutFileUrl }) => {
                   const urlRelativeToBase = getUrlRelativeToBase(url);
                   if (outDirectoryReason) {
                     let urlInsideOutDirectory = getUrlInsideOutDirectory(
@@ -267,7 +269,7 @@ ${renderFileContent(
                     }
                     const outRelativeUrl = urlToRelativeUrl(
                       urlInsideOutDirectory,
-                      sideEffectFileUrl,
+                      sideEffectMdFileUrl,
                       {
                         preferRelativeNotation: true,
                       },
@@ -311,7 +313,7 @@ ${renderFileContent(
           },
         },
         {
-          include,
+          include: filesystemActions,
           undoFilesystemSideEffects: !preserve,
         },
       );

package/src/side_effects/filesystem/spy_filesystem_calls.js

@@ -9,7 +9,7 @@ import {
   writeFileSync,
 } from "@jsenv/filesystem";
 import { URL_META } from "@jsenv/url-meta";
-import { yieldAncestorUrls } from "@jsenv/urls";
+import { ensurePathnameTrailingSlash, yieldAncestorUrls } from "@jsenv/urls";
 import { readFileSync, statSync } from "node:fs";
 import { pathToFileURL } from "node:url";
 import {
@@ -28,9 +28,20 @@ export const spyFilesystemCalls = (
   },
   { include, undoFilesystemSideEffects } = {},
 ) => {
-  const shouldReport = include
-    ? URL_META.createFilter(include, "file:///")
-    : () => true;
+  const getAction = include
+    ? (() => {
+        const associations = URL_META.resolveAssociations(
+          {
+            action: include,
+          },
+          "file:///",
+        );
+        return (url) => {
+          const meta = URL_META.applyAssociations({ url, associations });
+          return meta.action;
+        };
+      })()
+    : () => "compare";
 
   const _internalFs = process.binding("fs");
   const filesystemStateInfoMap = new Map();
@@ -58,35 +69,49 @@ export const spyFilesystemCalls = (
       // function did not have any effect on the file
       return;
     }
-    if (!shouldReport(fileUrl)) {
-      return;
-    }
-    if (undoFilesystemSideEffects && !fileRestoreMap.has(fileUrl)) {
-      if (stateBefore.found) {
-        fileRestoreMap.set(fileUrl, () => {
-          writeFileSync(fileUrl, stateBefore.buffer);
-        });
-      } else {
-        fileRestoreMap.set(fileUrl, () => {
-          removeFileSync(fileUrl, { allowUseless: true });
-        });
+    const action = getAction(fileUrl);
+    const shouldCompare =
+      action === "compare" ||
+      action === "compare_presence_only" ||
+      action === true;
+    if (action === "undo" || shouldCompare) {
+      if (undoFilesystemSideEffects && !fileRestoreMap.has(fileUrl)) {
+        if (stateBefore.found) {
+          fileRestoreMap.set(fileUrl, () => {
+            writeFileSync(fileUrl, stateBefore.buffer);
+          });
+        } else {
+          fileRestoreMap.set(fileUrl, () => {
+            removeFileSync(fileUrl, { allowUseless: true });
+          });
+        }
       }
     }
-    onWriteFile(fileUrl, stateAfter.buffer, reason);
+    if (shouldCompare) {
+      onWriteFile(fileUrl, stateAfter.buffer, reason);
+    }
+    // "ignore", false, anything else
   };
   const onWriteDirectoryDone = (directoryUrl) => {
-    if (!shouldReport(directoryUrl)) {
-      return;
-    }
-    if (undoFilesystemSideEffects && !fileRestoreMap.has(directoryUrl)) {
-      fileRestoreMap.set(directoryUrl, () => {
-        removeDirectorySync(directoryUrl, {
-          allowUseless: true,
-          recursive: true,
+    const action = getAction(directoryUrl);
+    const shouldCompare =
+      action === "compare" ||
+      action === "compare_presence_only" ||
+      action === true;
+    if (action === "undo" || shouldCompare) {
+      if (undoFilesystemSideEffects && !fileRestoreMap.has(directoryUrl)) {
+        fileRestoreMap.set(directoryUrl, () => {
+          removeDirectorySync(directoryUrl, {
+            allowUseless: true,
+            recursive: true,
+          });
         });
-      });
+      }
+    }
+    if (shouldCompare) {
+      onWriteDirectory(directoryUrl);
     }
-    onWriteDirectory(directoryUrl);
+    // "ignore", false, anything else
   };
   const restoreCallbackSet = new Set();
 
@@ -101,7 +126,9 @@ export const spyFilesystemCalls = (
     _internalFs,
     "mkdir",
     (directoryPath, mode, recursive) => {
-      const directoryUrl = pathToFileURL(directoryPath);
+      const directoryUrl = ensurePathnameTrailingSlash(
+        pathToFileURL(directoryPath),
+      );
       const stateBefore = getDirectoryState(directoryPath);
       if (!stateBefore.found && recursive) {
         const ancestorNotFoundArray = [];
@@ -110,7 +137,9 @@ export const spyFilesystemCalls = (
           if (ancestorState.found) {
             break;
           }
-          ancestorNotFoundArray.unshift(ancestorUrl);
+          ancestorNotFoundArray.unshift(
+            ensurePathnameTrailingSlash(ancestorUrl),
+          );
         }
         return {
           return: (fd) => {
@@ -151,6 +180,13 @@ export const spyFilesystemCalls = (
     },
     { execute: METHOD_EXECUTION_NODE_CALLBACK },
   );
+  /*
+   * Relying on open/close to detect writes is done to be able to catch
+   * write done async, not sure how to distinguish open/close done to write
+   * from open/close done to read file stat
+   * open/close for file stat are excluded because we compare stateBefore/stateAfter
+   * but ideally we would early return by detecting open/close is not for write operations
+   */
   const closeHook = hookIntoMethod(
     _internalFs,
     "close",

package/src/side_effects/log/log_side_effects.js

@@ -4,7 +4,7 @@ import { groupLogSideEffects } from "./group_log_side_effects.js";
 
 const logSideEffectsOptionsDefault = {
   prevent: true,
-  group: false,
+  group: true,
 };
 
 export const logSideEffects = (logSideEffectsOptions) => {

package/src/side_effects/render_side_effects.js

@@ -37,8 +37,7 @@ export const createBigSizeEffect =
 export const renderSideEffects = (
   sideEffects,
   {
-    sideEffectFileUrl,
-    outDirectoryUrl,
+    sideEffectMdFileUrl,
     generateOutFileUrl,
     generatedBy = true,
     titleLevel = 1,
@@ -50,6 +49,7 @@ export const renderSideEffects = (
       dedicatedFile: { line: 50, length: 5000 },
     }),
     errorStackHidden,
+    errorMessageTransform,
   } = {},
 ) => {
   const { rootDirectoryUrl, replaceFilesystemWellKnownValues } =
@@ -85,14 +85,14 @@ export const renderSideEffects = (
       markdown += "\n\n";
     }
     markdown += renderOneSideEffect(sideEffect, {
-      sideEffectFileUrl,
-      outDirectoryUrl,
+      sideEffectMdFileUrl,
       generateOutFileUrl,
       rootDirectoryUrl,
       titleLevel,
       getBigSizeEffect,
       replace,
       errorStackHidden,
+      errorMessageTransform,
       lastSideEffectNumber,
     });
   }
@@ -133,14 +133,14 @@ ${"  ".repeat(indent)}</sub>`;
 const renderOneSideEffect = (
   sideEffect,
   {
-    sideEffectFileUrl,
-    outDirectoryUrl,
+    sideEffectMdFileUrl,
     generateOutFileUrl,
     rootDirectoryUrl,
     titleLevel,
     getBigSizeEffect,
     replace,
     errorStackHidden,
+    errorMessageTransform,
     lastSideEffectNumber,
   },
 ) => {
@@ -152,8 +152,7 @@ const renderOneSideEffect = (
   }
   const { md } = sideEffect.render;
   let { label, text } = md({
-    sideEffectFileUrl,
-    outDirectoryUrl,
+    sideEffectMdFileUrl,
     generateOutFileUrl,
     replace,
     rootDirectoryUrl,
@@ -172,11 +171,12 @@ const renderOneSideEffect = (
     }
     text = renderText(text, {
       sideEffect,
-      sideEffectFileUrl,
+      sideEffectMdFileUrl,
       generateOutFileUrl,
       replace,
       rootDirectoryUrl,
       errorStackHidden,
+      errorMessageTransform,
     });
   }
   if (sideEffect.code === "source_code") {
@@ -208,11 +208,12 @@ const renderText = (
   text,
   {
     sideEffect,
-    sideEffectFileUrl,
+    sideEffectMdFileUrl,
     generateOutFileUrl,
     replace,
     rootDirectoryUrl,
     errorStackHidden,
+    errorMessageTransform,
   },
 ) => {
   if (text && typeof text === "object") {
@@ -224,7 +225,7 @@ const renderText = (
       }
       const callSiteRelativeUrl = urlToRelativeUrl(
         callSite.url,
-        sideEffectFileUrl,
+        sideEffectMdFileUrl,
         { preferRelativeNotation: true },
       );
       const sourceCodeLinkText = `${callSiteRelativeUrl}:${callSite.line}:${callSite.column}`;
@@ -250,14 +251,17 @@ const renderText = (
           typeof jsValue.stack === "string")
       ) {
         // return renderMarkdownBlock(text.value.stack);
-        const exception = createException(jsValue, { rootDirectoryUrl });
+        const exception = createException(jsValue, {
+          rootDirectoryUrl,
+          errorMessageTransform,
+        });
         const exceptionText = errorStackHidden
           ? `${exception.name}: ${exception.message}`
           : exception.stack || exception.message || exception;
         return renderPotentialAnsi(exceptionText, {
           stringType: "error",
           sideEffect,
-          sideEffectFileUrl,
+          sideEffectMdFileUrl,
           generateOutFileUrl,
           replace,
         });
@@ -267,7 +271,7 @@ const renderText = (
     if (text.type === "console") {
       return renderConsole(text.value, {
         sideEffect,
-        sideEffectFileUrl,
+        sideEffectMdFileUrl,
         generateOutFileUrl,
         replace,
       });
@@ -287,12 +291,12 @@ const renderText = (
 
 export const renderConsole = (
   string,
-  { sideEffect, sideEffectFileUrl, generateOutFileUrl, replace },
+  { sideEffect, sideEffectMdFileUrl, generateOutFileUrl, replace },
 ) => {
   return renderPotentialAnsi(string, {
     stringType: "console",
     sideEffect,
-    sideEffectFileUrl,
+    sideEffectMdFileUrl,
     generateOutFileUrl,
     replace,
   });
@@ -300,7 +304,7 @@ export const renderConsole = (
 
 const renderPotentialAnsi = (
   string,
-  { stringType, sideEffect, sideEffectFileUrl, generateOutFileUrl, replace },
+  { stringType, sideEffect, sideEffectMdFileUrl, generateOutFileUrl, replace },
 ) => {
   const rawTextBlock = renderMarkdownBlock(
     replace(string, { stringType }),
@@ -324,7 +328,7 @@ const renderPotentialAnsi = (
   );
   svgFileContent = replace(svgFileContent, { fileUrl: svgFileUrl });
   writeFileSync(svgFileUrl, svgFileContent);
-  const svgFileRelativeUrl = urlToRelativeUrl(svgFileUrl, sideEffectFileUrl);
+  const svgFileRelativeUrl = urlToRelativeUrl(svgFileUrl, sideEffectMdFileUrl);
   let md = `![img](${svgFileRelativeUrl})`;
   md += "\n\n";
   md += renderMarkdownDetails(`${rawTextBlock}`, {

package/src/side_effects/snapshot_side_effects.js

@@ -1,69 +1,71 @@
-import { urlToBasename } from "@jsenv/urls";
-import {
-  takeDirectorySnapshot,
-  takeFileSnapshot,
-} from "../filesystem_snapshot.js";
+import { writeFileSync } from "@jsenv/filesystem";
+import { urlToBasename, urlToFilename } from "@jsenv/urls";
+import { takeDirectorySnapshot } from "../filesystem_snapshot.js";
 import { createCaptureSideEffects } from "./create_capture_side_effects.js";
 import { renderSideEffects } from "./render_side_effects.js";
-
+/**
+ * Generate a markdown file describing code side effects. When executed in CI throw if there is a diff.
+ * @param {URL} sourceFileUrl
+ *        Url where the function is located (import.meta.url)
+ * @param {Function} fn
+ *        Function to snapshot
+ * @param {Object} snapshotSideEffectsOptions
+ * @param {string|url} snapshotSideEffectsOptions.outFilePattern
+ * @param {string|url} snapshotSideEffectsOptions.sideEffectMdFileUrl
+ *        Where to write the markdown file. Defaults to ./[]
+ * @param {string|url} snapshotSideEffectsOptions.rootDirectoryUrl
+ * @param {Object|boolean} [snapshotSideEffectsOptions.filesystemEffects]
+ * @param {boolean} [snapshotSideEffectsOptions.filesystemEffects.textualFilesInline=false]
+ *        Put textual files content in the markdown (instead of separate files).
+ *        Big files will still be put in dedicated files.
+ * @param {boolean} [snapshotSideEffectsOptions.filesystemEffects.preserve=false]
+ *        Preserve filesystem side effect when function ends. By default
+ *        filesystem effects are undone when function ends
+ * @param {url} [snapshotSideEffectsOptions.filesystemEffects.baseDirectory]
+ *        Urls of filesystem side effects will be relative to this base directory
+ *        Default to the directory containing @sourceFileUrl
+ * @return {Array.<Object>} sideEffects
+ */
 export const snapshotSideEffects = (
   sourceFileUrl,
   fn,
   {
-    sideEffectFileUrl,
-    outDirectoryPattern = "./side_effects/",
-    sideEffectFilePattern = "./side_effects/[basename].md",
-    outFilePattern = "./side_effects/[name]/[filename]",
-    generateOutFileUrl,
-    outDirectoryUrl,
+    sideEffectMdFileUrl,
+    outFilePattern = "_[source_filename]/[filename]",
     errorStackHidden,
+    throwWhenDiff,
     ...captureOptions
   } = {},
 ) => {
-  const name = urlToBasename(sourceFileUrl, true);
-  const basename = urlToBasename(sourceFileUrl);
-  if (sideEffectFileUrl === undefined) {
-    const sideEffectFileRelativeUrl = sideEffectFilePattern
-      .replaceAll("[basename]", basename)
-      .replaceAll("[name]", name);
-    sideEffectFileUrl = new URL(sideEffectFileRelativeUrl, sourceFileUrl);
-  } else {
-    sideEffectFileUrl = new URL(sideEffectFileUrl, sourceFileUrl);
-  }
-
-  const captureSideEffects = createCaptureSideEffects(captureOptions);
-  if (outDirectoryUrl === undefined) {
-    const outDirectoryRelativeUrl = outDirectoryPattern.replaceAll(
-      "[basename]",
-      basename,
-    );
-    outDirectoryUrl = new URL(outDirectoryRelativeUrl, sideEffectFileUrl);
-  }
-  if (generateOutFileUrl === undefined) {
-    generateOutFileUrl = (filename) => {
-      const outRelativeUrl = outFilePattern
-        .replaceAll("[name]", name)
-        .replaceAll("[basename]", basename)
-        .replaceAll("[filename]", filename);
-      const outFileUrl = new URL(outRelativeUrl, new URL("./", sourceFileUrl))
-        .href;
-      return outFileUrl;
-    };
-  }
-
-  const sideEffectFileSnapshot = takeFileSnapshot(sideEffectFileUrl);
+  const sourceName = urlToBasename(sourceFileUrl, true);
+  const sourceBasename = urlToBasename(sourceFileUrl);
+  const sourceFilename = urlToFilename(sourceFileUrl);
+  const generateOutFileUrl = (filename) => {
+    const outRelativeUrl = outFilePattern
+      .replaceAll("[source_name]", sourceName)
+      .replaceAll("[source_basename]", sourceBasename)
+      .replaceAll("[source_filename]", sourceFilename)
+      .replaceAll("[filename]", filename);
+    const outFileUrl = new URL(outRelativeUrl, new URL("./", sourceFileUrl))
+      .href;
+    return outFileUrl;
+  };
+  const outDirectoryUrl = generateOutFileUrl("");
+  sideEffectMdFileUrl =
+    sideEffectMdFileUrl || generateOutFileUrl(`${sourceFilename}.md`);
+  const captureSideEffects = createCaptureSideEffects({
+    ...captureOptions,
+    sourceFileUrl,
+  });
   const outDirectorySnapshot = takeDirectorySnapshot(outDirectoryUrl);
   const onSideEffects = (sideEffects) => {
     const sideEffectFileContent = renderSideEffects(sideEffects, {
-      sideEffectFileUrl,
-      outDirectoryUrl,
+      sideEffectMdFileUrl,
       generateOutFileUrl,
       errorStackHidden,
     });
-    sideEffectFileSnapshot.update(sideEffectFileContent, {
-      mockFluctuatingValues: false,
-    });
-    outDirectorySnapshot.compare();
+    writeFileSync(sideEffectMdFileUrl, sideEffectFileContent);
+    outDirectorySnapshot.compare(throwWhenDiff);
   };
   const returnValue = captureSideEffects(fn);
   if (returnValue && typeof returnValue.then === "function") {

package/src/side_effects/snapshot_tests.js

@@ -1,49 +1,66 @@
-import { urlToBasename, urlToRelativeUrl } from "@jsenv/urls";
-import {
-  takeDirectorySnapshot,
-  takeFileSnapshot,
-} from "../filesystem_snapshot.js";
+import { writeFileSync } from "@jsenv/filesystem";
+import { urlToBasename, urlToFilename, urlToRelativeUrl } from "@jsenv/urls";
+import { takeDirectorySnapshot } from "../filesystem_snapshot.js";
 import { getCallerLocation } from "../get_caller_location.js";
 import { createCaptureSideEffects } from "./create_capture_side_effects.js";
 import { renderSideEffects, renderSmallLink } from "./render_side_effects.js";
 
 /**
- * Generate a markdown file describing all test side effects. When executed in CI throw if there is a diff.
- * @param {URL} testFileUrl
+ * Generate a markdown file describing test(s) side effects. When executed in CI throw if there is a diff.
+ * @param {URL} sourceFileUrl
  * @param {Function} fnRegisteringTest
  * @param {Object} snapshotTestsOptions
- * @param {string|url} snapshotTestsOptions.sideEffectFileUrl
+ * @param {string|url} snapshotTestsOptions.outFilePattern
  * @param {string|url} snapshotTestsOptions.rootDirectoryUrl
- * @return {Array.<Object>} sideEffects
+ * @param {Object|boolean} [snapshotTestsOptions.filesystemEffects]
+ * @param {boolean} [snapshotTestsOptions.filesystemEffects.textualFilesInline=false]
+ *        Put textual files content in the markdown (instead of separate files).
+ *        Big files will still be put in dedicated files.
+ * @param {boolean} [snapshotTestsOptions.filesystemEffects.preserve=false]
+ *        Preserve filesystem side effect when function ends. By default
+ *        filesystem effects are undone when function ends
+ * @param {url} [snapshotTestsOptions.filesystemEffects.baseDirectory]
+ *        Urls of filesystem side effects will be relative to this base directory
+ *        Default to the directory containing @sourceFileUrl
  */
 export const snapshotTests = async (
-  testFileUrl,
+  sourceFileUrl,
   fnRegisteringTest,
   {
-    testName = urlToBasename(testFileUrl, true),
-    sideEffectFileUrl,
-    outDirectoryPattern = "./side_effects/",
-    sideEffectFilePattern = "./side_effects/[test_basename].md",
-    outFilePattern = "./side_effects/[test_name]/[test_scenario]/[filename]",
+    outFilePattern = "./_[source_filename]/[filename]",
+    filesystemActions = {
+      "**": "compare",
+      // "**/*.svg": "compare_presence_only",
+    },
     rootDirectoryUrl,
     generatedBy = true,
     linkToSource = true,
     linkToEachSource,
     errorStackHidden,
+    errorMessageTransform,
     logEffects,
     filesystemEffects,
     throwWhenDiff = process.env.CI,
   } = {},
 ) => {
-  const testBasename = urlToBasename(testFileUrl);
-  if (sideEffectFileUrl === undefined) {
-    const sideEffectFileRelativeUrl = sideEffectFilePattern
-      .replaceAll("[test_name]", testName)
-      .replaceAll("[test_basename]", testBasename);
-    sideEffectFileUrl = new URL(sideEffectFileRelativeUrl, testFileUrl);
-  } else {
-    sideEffectFileUrl = new URL(sideEffectFileUrl, testFileUrl);
-  }
+  const sourceName = urlToBasename(sourceFileUrl, true);
+  const sourceBasename = urlToBasename(sourceFileUrl);
+  const sourceFilename = urlToFilename(sourceFileUrl);
+  const generateOutFileUrl = (outFilename) => {
+    const outFileRelativeUrl = outFilePattern
+      .replaceAll("[source_name]", sourceName)
+      .replaceAll("[source_basename]", sourceBasename)
+      .replaceAll("[source_filename]", sourceFilename)
+      .replaceAll("[filename]", outFilename);
+    const outFileUrl = new URL(outFileRelativeUrl, sourceFileUrl).href;
+    return outFileUrl;
+  };
+  const outDirectoryUrl = generateOutFileUrl("");
+  const outDirectorySnapshot = takeDirectorySnapshot(
+    outDirectoryUrl,
+    filesystemActions,
+  );
+  const sideEffectMdFileUrl = generateOutFileUrl(`${sourceFilename}.md`);
 
   const dirUrlMap = new Map();
   const sideEffectsMap = new Map();
@@ -65,12 +82,14 @@ export const snapshotTests = async (
 
   const activeTestMap = onlyTestMap.size ? onlyTestMap : testMap;
   const captureSideEffects = createCaptureSideEffects({
+    sourceFileUrl,
     rootDirectoryUrl,
     logEffects,
     filesystemEffects,
+    filesystemActions,
   });
   let markdown = "";
-  markdown += `# ${testName}`;
+  markdown += `# ${sourceName}`;
   if (generatedBy) {
     let generatedByLink = renderSmallLink(
       {
@@ -80,8 +99,8 @@ export const snapshotTests = async (
       {
         prefix: "Generated by ",
         suffix:
-          linkToSource && testFileUrl
-            ? generateExecutingLink(testFileUrl, sideEffectFileUrl)
+          linkToSource && sourceFileUrl
+            ? generateExecutingLink(sourceFileUrl, sideEffectMdFileUrl)
             : "",
       },
     );
@@ -89,6 +108,7 @@ export const snapshotTests = async (
     markdown += generatedByLink;
   }
 
+  const scenarioDirs = [];
   for (const [scenario, { fn, callSite }] of activeTestMap) {
     markdown += "\n\n";
     markdown += `## ${scenario}`;
@@ -99,43 +119,40 @@ export const snapshotTests = async (
     });
     sideEffectsMap.set(scenario, sideEffects);
     const testScenario = asValidFilename(scenario);
-    let outDirectoryRelativeUrl = outDirectoryPattern
-      .replaceAll("[test_name]", testName)
-      .replaceAll("[test_scenario]", testScenario);
-    const outDirectoryUrl = new URL(outDirectoryRelativeUrl, testFileUrl);
-    const outDirectorySnapshot = takeDirectorySnapshot(outDirectoryUrl, {
-      pattern: {
-        "**/*": true,
-        "**/*.svg": "presence_only",
-      },
-    });
-    const generateOutFileUrl = (filename) => {
-      const outFileRelativeUrl = outFilePattern
-        .replaceAll("[test_name]", testName)
-        .replaceAll("[test_basename]", testBasename)
-        .replaceAll("[test_scenario]", testScenario)
-        .replaceAll("[filename]", filename);
-      const outFileUrl = new URL(outFileRelativeUrl, testFileUrl).href;
-      return outFileUrl;
+    scenarioDirs.push(testScenario);
+    const generateScenarioOutFileUrl = (outfilename) => {
+      return generateOutFileUrl(`${testScenario}/${outfilename}`);
     };
-    const outFileDirectoryUrl = generateOutFileUrl("");
-    dirUrlMap.set(scenario, outFileDirectoryUrl);
+    const scenarioOutDirectoryUrl = generateScenarioOutFileUrl("");
+    dirUrlMap.set(scenario, scenarioOutDirectoryUrl);
     const sideEffectsMarkdown = renderSideEffects(sideEffects, {
-      sideEffectFileUrl,
-      outDirectoryUrl,
-      generateOutFileUrl,
+      sideEffectMdFileUrl,
+      generateOutFileUrl: generateScenarioOutFileUrl,
       generatedBy: false,
       titleLevel: 3,
       errorStackHidden,
+      errorMessageTransform,
     });
-    outDirectorySnapshot.compare(throwWhenDiff);
     markdown += sideEffectsMarkdown;
   }
-  const sideEffectFileSnapshot = takeFileSnapshot(sideEffectFileUrl);
-  sideEffectFileSnapshot.update(markdown, {
-    mockFluctuatingValues: false,
-    throwWhenDiff,
-  });
+  // if (sideEffectFilePattern === "./side_effects/[filename]/[filename].md") {
+  //   const scenarioParentDirUrl = new URL("./", sideEffectFileUrl);
+  //   const dirContent = readDirectorySync(scenarioParentDirUrl);
+  //   for (const entry of dirContent) {
+  //     const entryUrl = new URL(entry, scenarioParentDirUrl);
+  //     if (!readEntryStatSync(entryUrl).isDirectory()) {
+  //       continue;
+  //     }
+  //     if (scenarioDirs.includes(entry)) {
+  //       continue;
+  //     }
+  //     removeDirectorySync(entryUrl, {
+  //       recursive: true,
+  //     });
+  //   }
+  // }
+  writeFileSync(sideEffectMdFileUrl, markdown);
+  outDirectorySnapshot.compare(throwWhenDiff);
 
   return { dirUrlMap, sideEffectsMap };
 };